trends_read

Чтение трендов для указанных переменных в заданном интервале времени в формате интервальной выборки

Параметры запроса

• pult_apikey (string): API-ключ.

• vars (array): Массив запросов. Каждый элемент массива описывает запрос тренда соответствующей переменной и должен иметь следующий формат:

    [<varname>, <time1>, <time2>, <rows>, <true_time_intervals>]
  

  • varname (string): Глобальное имя переменной.

  • time1 (uint64, опционально): Начало интервала, timestamp c миллисекундами.

  • time2 (uint64, опционально): Конец интервала, timestamp c миллисекундами.

  • rows (int, опционально): Максимальное количество возвращаемых записей одного тренда. Если параметр не задан, rows берется равным параметру max_rows в настройках сервиса trends (3000 по умолчанию).

    Если количество записей в диапазоне между time1 и time2 превышает rows, диапазон разбивается на rows отрезков и возвращаются только первые записи каждого отрезка (см. параметр true_time_intervals). Для получения гарантированного сплошного списка значений используйте API-функцию trends_log.

  • true_time_intervals (bool, опционально): Использовать равномерные временные интервалы. Параметр управляет методом выборки данных из временного ряда, если заданы time1 и time2.

    Если true_time_intervals == false (по умолчанию), выборка записей из временного ряда производится равномерно по индексам, то есть:

    • Диапазон индексов между time1 и time2 делится на rows равных отрезков.
    • Из каждого отрезка выбирается первая запись.
    • Равномерное распределение по времени не гарантируется — интервалы между временными метками могут быть неравны, если данные записывались с переменным интервалом.
    • Данный метод наиболее производительный, т.к. не зависит от количества записей в запрашиваемом временном диапазоне.

    Если true_time_intervals == true, выборка записей из временного ряда производится равномерно по времени:

    • Диапазон индексов между time1 и time2 делится на rows равных временных отрезков методом бинарного поиска.
    • Из каждого отрезка выбирается первая запись;
    • Гарантируется равномерное распределение по времени (возвращаются записи, ближайшие к границам равных временных отрезков).
    • Данный метод менее производительный, т.к. требует нескольких итераций для поиска ближайших записей.

Возвращаемые значения

• Объект со следующей структурой:

    {
        "time1": <начало интервала>,
        "time2": <конец интервала>,
        "data": [
            [<записи по тренду для переменной_1>],
            [<записи по тренду для переменной_2>],
            ...
            [<записи по тренду для переменной_N>]
        ],
        "total": [
            <полное кол-во записей в интервале для переменной_1>,
            <полное кол-во записей в интервале для переменной_2>,
            ...
            <полное кол-во записей в интервале для переменной_N>
        ]
    }
  

  Запись по тренду представляет собой массив со следующими полями:

    [<time>,<value>,<error>]
  

  • time (uint64): время изменения переменной (смещение в мс от time1)
  • value (double): значение переменной в момент time
  • error (int16): код ошибки в момент time (если есть)

Особенности

• Для минимизации трафика запрос и ответ определен в формате массивов
• Первые возвращаемые записи всегда ищутся ближайшие к time1, но имеющие time < time1. Значение этих записей показывает значение переменных на момент time1.
• Возвращаемое значение total показывает ПОЛНОЕ (а не возвращенное) количество записей в запрашиваемом диапазоне. total == возвращенное количество записей означает, что выборка записей была сплошной - возвращены все записи диапазона, без разбивки по отрезкам.

Пример

• Пример WS-запроса:

    {
        "jsonrpc":"2.0",
        "id":1,
        "method":"trends_read",
        "params":{
            "pult_apikey":"31269DCE4F983A31FBE8B88DF67CDAE2",
            "vars":[
                ["P6_N6_temp_supply",1747148123000,1747148133000,1000,0],
                ["P6_N6_temp_outdoor",1747148123000,1747148133000,1000,0]
            ],
        }
    }
  

• Пример WS-ответа:

    {
        "jsonrpc":"2.0",
        "id":1,
        "result":{
            "time1": 1747148123000,
            "time2": 1747148133000,
            "data": [
                [
                    [-448, 13.7],
                    [1976, 13.66],
                    [1044, 13.62],
                    ...
                ],
                [
                    [-1487, 12.87],
                    [3015, 12.88],
                    [1044, 12.87], 
                    ...
                ]
            ],
            "total": [8, 8]
        }
    }
  

• Пример HTTP-запроса:

  https://webscada.ru/api/trends_read?pult_apikey=31269DCE4F983A31FBE8B88DF67CDAE2&@vars=[[%22P6_N6_temp_supply%22,1747148123000,1747148133000,3000,0],[%22P6_N6_temp_outdoor%22,1747148123000,1747148133000,3000,0]]